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Prototype  Real-Time  Monitor:  User’s  Manual 

Abstract.  This  report  defines  the  user  interface  to  the  prototype  real-time  monitor 
(RTM).  It  defines  the  concepts  and  commands  needed  by  a  software  engineer  to  use 
the  RTM.  In  addition  to  defining  the  user  interface,  the  report  explains  the  steps 
needed  to  tailor  the  RTM  to  work  with  the  user's  application. 

Intended  Audience 

The  manual  is  intended  for  software  engineers  familiar  with  the  Ada®1  language  and  the  con¬ 
cepts  involved  with  software  integration  and  testing. 

Associated  Documents 

•  Reference  Manual  for  the  Ada  Programming  Language  [Ada  83] 

•  Prototype  Real-Time  Monitor:  Requirements  [ D'lppolito  87] 

•  Prototype  Real-Time  Monitor:  Design  [Van  Scoy  87a] 

•  Prototype  Real-Time  Monitor:  Ada  Code  [Van  Scoy  87b] 

•  User's  Manual  for  a  Form  Generator  System  in  Ada  [Texas  Instalments  85a] 

•  User's  Manual  for  an  ANSI  X3.64  Compatible  Virtual  Terminal  in  Ada  [Texas  Instru¬ 
ments  85b] 

Context  of  Report 

The  prototype  RTM  described  in  this  report  was  built  to  address  two  specific  technical  questions 
raised  by  the  Ada  Simulator  Validation  Program  (ASVP)  contractors: 

1.  How  can  user  tools  find,  access,  and  display  data  hidden  in  the  bodies  of  Ada 
applications? 

2.  How  can  user  tools  be  layered  on  top  of  Ada  applications? 

The  prototype  is  documented  by  this  report  because  the  ASVP  contractors  had  a  need  for  a 
monitor  tool,  but  did  not  have  the  contract  resources  to  develop  one.  The  prototype  RTM  is 
intended  to  be  a  simple  tool  that  is  easily  rehosted  and  extended.  It  is  not  intended  to  be  an 
example  of  what  a  well-documented  system  should  include.  Since  it  was  a  prototyping  effort,  no 
standard  documentation  or  development  methods  were  applied.  Also,  we  did  not  attempt  to  solve 
all  the  traditional  “monitor"  problems. 


'Ada  is  a  registered  trademark  of  the  U  S  Government  (Ada  Joint  Program  Office) 


1.  Basic  Concepts 

The  real-time  monitor,  in  its  simplest  form,  is  a  tool  which  a  software  engineer  can  use  to  read 
and  write  data  memory  in  an  executing  application.  The  tool  allows  the  engineer  to  do  this 
without  requiring  any  prior  knowledge  about  which  memory  locations  (i.e.,  variables)  need  to  be 
operated  on.  The  RTM  has  no  explicit  control  over  the  application.  This  particular  monitor  is 
called  real-time  because  it  is  intended  to  be  used  in  conjunction  with  real-time  applications  and 
run  in  whatever  spare  time  is  available  to  the  processor.  In  this  way,  it  will  not  adversely  perturb 
the  essential  timing  of  the  application.  Some  of  the  operations  required  to  set  up  a  monitoring 
session  may  require  a  considerable  amount  of  CPU  time  and  user  thought  and  can  be  done 
without  the  active  participation  of  the  application;  these  can  legitimately  be  considered  off-line 
functions. 

1.1.  Definitions 

The  following  definitions  describe  the  basic  concepts  which  are  elaborated  in  the  remainder  ot 
this  document. 

Variable  A  legal  Ada  variable  that  exists  in  the  application  and  can  be  monitored 

Variable  DatabaseThe  collection  of  all  variables  in  the  application  that  are  accessible  to  the  user 
through  the  RTM. 

Page  A  collection  of  variables  that  are  read  and  displayed  to  the  user  as  a  unit 

1.2.  Command  Summary 

The  commands  used  by  the  user  to  control  RTM  operations  can  be  summarized  as  follows: 

CHECK  Checks  all  the  variables  on  a  page  for  existence  and  accessibility. 

EDIT  Creates  or  modifies  a  page. 

READ  Accesses  a  single  variable  in  the  application. 

SET  Assigns  a  new  value  to  a  single  variable  in  the  application. 

START  Begins  reading  a  page  of  variables  from  the  application  and  periodically  dis¬ 

plays  the  page  to  the  user. 

STOP  Terminates  the  reading  of  a  page  begun  by  a  START  command. 

QUIT  Terminates  the  RTM. 

The  full  description  of  the  commands,  including  examples,  can  be  found  in  Appendix  A,  starting 
on  page  17. 


CMU/SEI-87-TR-37 


3 


1.3.  Prototype  Restrictions 


One  important  point  to  keep  in  mind  is  that  this  manual  describes  a  prototype  RTM,  not  a 
production-quality  RTM.  As  such,  a  number  of  simplifications  and  restrictions  to  the  RTM  have 
been  made.  These  restrictions  are: 


•  Single  display  device 

•  VT100  type  terminal 

•  80  columns  by  24  lines 

•  lines  1  - 19  for  use  by  user 

•  lines  20  -  24  for  use  by  RTM 

•  keyboard  input  only 

•  No  simultaneous  input  and  output  to  the  display  device  (i.e.,  screen  updating  halts 
during  user  command  entry). 

•  Only  integer,  real,  and  enumeration  types  can  be  displayed  (more  complex  types  can 
be  displayed  by  breaking  them  down  into  these  components,  or  the  user  can  imple¬ 
ment  display  routines  for  more  complex  structures). 

•  Ada  task  type  variables  are  not  accessible  for  display  or  modification. 

•  Ada  access  type  variables  are  not  accessible  for  display  or  modification,  but  the 
underlying  objects  are  accessible  (i.e.,  the  RTM  does  not  display  the  address  that  is 
the  value  of  an  access  type). 

•  Ada  constants  are  not  accessible  for  modification. 

•  Generation  of  the  variable  database  and  associated  conversion  routines  are  the  re¬ 
sponsibility  of  the  user. 

•  Only  one  page  of  variables  can  be  displayed  (i.e.,  be  active)  at  a  time. 
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2.  Selecting  Ada  Variables 

Selection  of  Ada  variables  (objects)  lor  page  definition  or  variable  manipulation  purposes  is  ac¬ 
complished  by  specifying  the  full  Ada  variable  name2  using  dot  notation,  which  represents  the 
object  of  interest.  For  example,  an  Ada  variable  process_controlllng_parameter  in  a  package 
Controller_A  which  is  “withed“  by  the  main  procedure  Real_Time_Appllcatlon  would  be  speci¬ 
fied  as  follows: 

R*al_Time_Application . Controller_A . proces3_controlling_parameter 

All  Ada  variables  referenced  by  the  user  are  checked  for  existence  in  the  variable  database 
when. 

•  a  START  command  is  issued 

•  a  CHECK  command  is  issued 

•  a  READ  command  is  issued 

•  a  SET  command  is  issued 

This  checking  is  rone  by  attempting  to  locate  the  variable  in  the  variable  database.  If  a  variable 
cannot  be  found  in  the  database,  an  error  message  is  issued  in  all  cases.  If  this  happens  when 
processing  a  READ  or  SET  command,  the  command  is  ignored.  If  this  happens  in  a  START 
command,  the  variable  is  deleted  from  the  display  page,  but  any  legal  variables  on  the  page  will 
be  processed  normally. 


?No  shorthand  notation  is  available  in  the  prototype  RTM 
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3.  Variable  Manipulation 


The  user  can  interactively  view  and  modify  data  on  an  individual  variable  basis.  This  is  done 
using  the  following  commands: 

READ  Reads  the  current  value  of  the  specified  Ada  variable  and  displays  it  on  the 

user’s  terminal. 

SET  Replaces  the  current  value  of  the  user-specified  Ada  variable  with  the  user- 

specified  value. 

The  values  displayed  will  reflect  the  type  of  Ada  variable,  and  similarly,  the  value  expected  for 
input  must  reflect  the  type  of  Ada  variable.  Both  of  these  commands  perform  one-time-only 
operations  (which  is  different  from  the  START  command  that  initiates  a  continuing  operation). 
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4.  Page  Definition 

The  RTM  provides  basic  page  definition  facilities  that  allow  the  user  to  define  pages  for  data 
collection  purposes  (i.e.,  a  page  to  be  monitored). 

The  user  creates  and  modifies  pages  by  using  the  EDIT  command.  All  page  editing  is  done  via  a 
forms  management  system  that  allows  the  user  to  move  around  the  screen  using  cursor  keys  and 
to  define  the  variables  on  the  page  using  the  keypad.  Additional  detailed  information  on  how 
editing  a  page/form  is  accomplished  can  be  found  in  the  User's  Manual  for  a  Form  Generator 
System  in  Ada  (Texas  Instruments  85a].  What  follows  is  a  brief  overview  of  the  process  and  a 
detailing  of  the  conventions  expected  by  the  RTM. 

A  page,  as  discussed  earlier,  is  a  collection  of  variables  that  are  read  and  displayed  as  a  group. 
The  creation  of  this  group  is  done  by  the  forms  management  system.  This  system  views  each 
page  as  a  form,  and  on  that  form  are  fields  (which  the  RTM  treats  as  variable  names).  Thus,  the 
creation  of  a  page  consists  of  creating  a  new  form  (page)  and  defining  the  fields  (variables)  that 
will  reside  on  that  form  (page). 

The  first  step  in  defining  a  new  page  is  to  issue  the  EDIT();  command.  The  RTM  will  then 
respond  with  the  menu  shown  in  Figure  4-1. 
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Figure  4-1:  Edit  Menu 

These  options  are  rather  self  explanatory: 

C  Creates  a  new  form  and  puts  the  user  into  edit  mode. 

L  Recalls  a  previously  saved  form  for  editing. 

E  Edits  the  form  currently  in  memory  (useful  for  making  incremental  changes  to  a  form  and 
available  only  after  a  C  or  L  command). 

M  Edits  the  characteristics  of  the  form,  such  as  row/column  dimensions  and  screen  position. 

S  Stores  a  form  on  disk. 

Q  Exits  the  editing  session  (not  the  RTM). 

When  a  new  page  is  created,  the  user  is  asked  to  determine  the  form's  attributes  using  the  menu 
shown  in  Figure  4-2. 


The  Interactive  Form  Generator 

Choose  "one"  of  the  following: 

C  -  create  a  new  form 
L  -  load  an  external  form 
E  -  edit  the  current  form 
M  -  modify  the  form' s  attributes 
S  -  save  the  current  form 
Q  -  quit 

Selection:  _ 


Here  is  where  the  prototype  restrictions  on  screen  size  have  an  impact.  The  user  should  not  (the 


Figure  4-2:  Form  Attributes  Menu 

RTM  cannot  enforce  this,  that  is  why  it  is  a  convention)  define  a  form  that  overlaps  lines  20 
through  24,  which  are  reserved  by  the  RTM. 

Once  the  form/page  attributes  are  set  (which  can  be  changed  later  using  the  M  option  above),  a 
completely  blank  page  is  presented  to  the  user.  The  user  is  now  free  to  move  about  the  screen 
using  the  cursor  keys.  Text  can  now  be  typed  anywhere  on  the  screen.  This  text  will  form  the 
trim  for  the  page,  but  does  not  constitute  a  variable.  To  place  a  variable  on  the  screen,  the  user 
must  position  the  cursor  where  the  variable  is  to  be  placed  and  using  the  keypad  shown  in  Figure 
4-3,  enter  a  7.  (There  is  a  complete  discussion  of  all  the  keypad  commands  in  the  Forms  Gener¬ 
ator  User's  Manual  [ Texas  Instruments  85a].)  The  RTM  responds  with  the  menu  in  Figure  4-4. 

+ - + - + - + - + 

|  PFl  |  PF2  |  PF3  |  PF4  | 

I  I  I  Exit  |  Delete | 

| Command |  Help  |  Form  |  Line  | 

+ - + - + - + - + 

I  7  |  8  |  9  |  -  | 

Create |  Modify |  Delete |  Delete | 

|  Field  |  Field  |  Field  |  Eoln  | 

+ - + - + - + - + 

I  4  |  5  |  6  |  ,  I 

|  Copy  |  Move  |  |  Delete  | 

I  Field  |  Field  |  I  Char  | 

+ - + - + - + - + 

I  1  I  2  |  3  |  I 

|  Copy  |  Move  |  I  Enter  | 

I  Line  |  Line  |  I  I 

+ - + - + - +  Accept  | 

I  0  I  -  I  Form  | 

|  Insert  I  Insert |  I 

|  Line  |  Char  |  | 

+ - + - + - + 

Figure  4-3:  VT 1 00  Keypad  Definition 


Field  name: 

Field  length: 

Character: 

(1  -  alphabetic. 

2  -  numeric 

limits 

3  -  alphanumeric. 

4  -  not  limited) 

Display: 

(1  -  normal 

2  -  secondary 

rendition 

3  -  reverse 

4  -  underline) 

Field  mode: 

(1  -  input /output 

2  -  output  only) 

Initial  value: 


Figure  4-4:  Field  Definition  Menu 


What  the  RTM  expects  the  user  to  enter  in  these  fields  is  shown  in  Figure  4-5. 


Field  name: 

full  Ada  path 

name  of  variable 

Field  length: 

display  size, 

in  characters,  of  object 

Character 

limits: 

4 

Display 

rendition: 

user' s  choice 

Field  mode: 

2 

Initial  value: 

not  used 

Figure  4-5:  Field  Definition  Conventions 


The  user  can  create  as  many  or  as  few  fields  as  will  fit  into  the  19  lines  available.  When  all  the 
variables  are  entered  as  fields,  the  field  definition  mode  is  terminated  by  entering  a  PF3  from  the 
keypad,  at  which  point  the  main  editing  menu  is  presented  again.  At  this  point,  the  user  must 
explicitly  save  the  page  by  issuing  the  S  command  shown  in  Figure  4-1  and  supply  a  name  for 
the  page.  Once  saved,  the  page  is  available  for  later  use  by  the  RTM  for  display  purposes  or 
subsequent  modification  by  editing. 

A  command  closely  related  to  EDIT  is  CHECK.  Since  the  forms  management  system  has  no 
direct  knowledge  of  the  variable  database  maintained  by  the  RTM,  the  CHECK  command  should 
be  used  after  editing  a  page  to  insure  that  all  the  variables  defined  on  the  page  are  accessible  to 
the  RTM. 

These  two  commands  also  allow  pages  to  be  created  and  checked  off  line,  i.e.,  without  an  ex¬ 
ecuting  application.  This  allows  the  time-consuming  page  editing  operation  to  take  place  prior  to 
using  the  RTM  to  debug  or  tune  an  application.  It  can  also  save  CPU  time  in  those  cases  where 
the  RTM  and  the  application  are  required  to  share  a  CPU,  or  where  the  RTM  is  rapidly  updating 
the  display. 
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5.  Page  Management 


The  capabilities  tor  managing  all  the  pages  defined  by  the  user  are  split  between  the  forms 
management  system  discussed  previously  and  the  host  computer  operating  system.  The  basic 
capabilities  of  page  management  are: 

Page  Operation  Method 

Copy  This  can  be  done  two  ways: 

•  via  the  forms  management  system  by  loading  using  the  L  option, 
editing  the  form,  and  then  storing  the  form  (using  the  S  option) 
under  a  new  name 

•  via  the  operating  system  by  using  the  a  copy  command  (like  copy 
on  VMS  systems  or  cp  on  Unix  systems) 


Delete 


Directory 


This  is  done  by  simply  deleting  the  appropriate  page  at  the  operating  system 
level.  Neither  the  RTM  nor  the  forms  management  system  imposes  any 
form/page  naming  conventions  on  the  user,  so  it  is  incumbent  upon  the  user  to 
keep  track  of  page  names.  Perhaps  the  easiest  solution  to  organizing  pages 
is  to  create  a  page  directory,  and  always  execute  the  RTM  from  that  directory. 

Again,  this  is  handled  at  the  operation  system  level  and  it  is  the  user's  respon¬ 
sibility  to  know  the  difference  between  page  file  names  and  any  other  file 
names  in  the  directory. 
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6.  Page  Control 

Once  the  user  has  created  a  page  that  specifies  Ada  variables  for  data  collection  purposes,  the 
page  can  be  activated  for  display  purposes  using  the  START  command.  The  data  collection  and 
screen  refresh  both  take  place  at  the  update  rate  specified  in  the  command.  Once  the  START 
command  is  issued,  data  collection  and  displaying  take  place  automatically,  without  user  inter¬ 
vention.  The  START  also  places  the  terminal  into  an  asynchronous  input  mode.  The  normal 
mode  of  input  is  for  the  RTM>  prompt  to  be  available  to  the  user  all  times,  but  when  a  page  is 
actively  being  displayed,  this  interferes  with  output  of  data.  To  alleviate  this  problem,  no  prompt 
is  presented  to  the  user.  This  does  not  mean  that  the  user  has  lost  control  of  the  RTM;  the  user 
simply  has  to  hit  any  key  and  the  RTM>  prompt  will  appear  and  a  command  can  be  entered. 

This  also  accomplishes  a  hold/resume  option  for  page  updating.  While  the  RTM  is  waiting  for  the 
user  to  enter  a  command,  no  updates  are  being  done  to  the  screen.  Once  a  command  is  entered 
and  processed,  updating  of  the  screen  resumes  (assuming  the  page  was  not  terminated,  which 
we  discuss  below).  Thus,  a  hold  (cease  updating)  is  a  return,  and  a  resume  (restart  updating)  is 
a  second  return. 

Once  a  page  is  no  longer  needed  on  the  display,  it  can  be  terminated  using  a  STOP  command. 
This  removes  the  page  from  the  display,  terminates  collection  of  the  data  from  the  variables 
specified  on  the  page,  and  returns  the  RTM  to  normal  input  mode  (since  only  one  page  can  be 
active  in  the  prototype). 
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Appendix  A:  Command  Language  Summary 

Conventions  Used  in  this  Appendix 

The  command  syntax  shown  in  this  appendix  is  that  o(  an  Ada  procedure  call  (see  Section  6.4  in 
[Ada  83]);  that  is,  all  RTM  commands  are  invoked  by  an  Ada  procedure  call,  which  implies  that 
case  and  spacing  are  not  significant.  Several  additional  conventions  in  delining  the  command 
syntax: 


Convention 

Meaning 

#### 

any  legal  Ada  variable  name 

any  legal  page  name 

nnnn 

any  Ada  value  (integer,  real,  enumeration,  etc.) 

x.xx 

any  legal  real  number 

my_variabte 

any  Ada  code 

x.y.foo 

any  user-entered  text 

Enter  Data> 

any  RTM  generated  output 

In  this  appendix,  the  basic  format  for  each  command  is; 

•  synopsis 

•  syntax 

•  parameters,  if  needed 

•  description 

•  examples 

•  exceptions,  if  needed 


CHECK 


CHECK 


SYNTAX 


Checks  the  Ada  variables  on  the  specified  page  for  availability  in  the  variable 
database. 


CHECK  (Page  =>  page_spec); 


PARAMETERS 


page_spec 

Specifies  the  page  on  which  checking  is  to  take  place.  This  page_spec  may 
include  a  path  name  for  the  page  file  (as  shown  below). 


DESCRIPTION 


The  CHECK  command  retrieves  the  specified  page  for  analysis.  This  analysis 
consists  of  checking  the  Ada  variables  defined  on  the  page  for  existence  in  the 
variable  database. 

This  command  can  be  used  in  conjunction  with  the  EDIT  command  to  develop 
the  pages  of  Ada  variables  off  line.  These  pages  can  be  created  using  the  page 
editor,  and  then  checked  against  the  variables  available  in  the  variable  database, 
with  appropriate  changes  made  using  the  page  editor.  This  off-line  activity  will 
allow  the  user  to  prepare  for  the  monitoring  process  ahead  of  time. 


EXAMPLES 


Check  (Page  •=>  [rtm.page_definition] test  _page)  ; 

Checks  the  Ada  variables  specified  on  the  page,  test_page,  for  existence  in  the 
variable  database. 


QUIT 


QUIT 

Exits  the  current  RTM  session. 


SYNTAX 

QUIT  (); 


DESCRIPTION 

The  QUIT  command  exits  the  current  monitoring  session  and  returns  the  user  to 
operating  system  or  application  control. 


EXAMPLES 

O  Qui  t  ()  ; 

Terminates  the  current  RTM  session. 


READ 


Reads  the  current  value  of  the  specified  Ada  variable  and  displays  it  on  the 
user's  terminal. 


SYNTAX 

READ  (Name  =>  ada_variable); 


PARAMETERS 

ada_variable 

The  name  of  the  Ada  variable  that  the  user  wants  read. 


DESCRIPTION 

! 


The  READ  command  reads  the  current  state  of  the  Ada  variable  specified  by  the 
user  and  displays  it  on  the  user's  terminal.  This  command  is  used  to  examine 
the  values  of  individual  Ada  variables  in  the  application  being  monitored  on  a 
one-time  basis.  This  command  can  be  issued  before  and/or  after  setting  an  Ada 
variable  (see  the  SET  command)  to  check  the  value  of  the  Ada  variable. 


EXAMPLES 


o 


© 


© 


o 


Read (Name  =>  engine. rpm) ; 

The  Variable:  engine. rpm 
has  the  value:  6032.24 

Reads  the  current  value  of  the  Ada  variable  engine.rpm  and  displays  it  on  the 
user's  terminal. 

Read  (Name  «*>  test_stub.my_record.  integer  jpart)  ; 

The  Variable:  test__stub.my_record.  integer_part 
has  the  value:  194 

Reads  the  current  value  of  the  integer_part  component  of  the  record  my_record 
and  displays  it  on  the  user’s  terminal. 

Read(Name  *>  fuel_system. status  (tank_l) ) ; 

The  Variable:  fuel_system. status (tank_l) 
has  the  value:  full 

Reads  the  current  value  of  the  tank_l  component  of  the  array  status  and  dis¬ 
plays  ft  on  the  user's  terminal. 

Read (Name  m>  my_pointer) ; 

The  Variable:  my_jpointer 
has  the  value:  1657 

Reads  the  current  value  of  the  object  pointed  at  by  my_po!nter  and  displays  it 
on  the  user's  terminal. 


READ 


SET 


Sets  the  Ada  variable  to  the  specified  value. 


SYNTAX 

SET  (Name  =>  ada_variable, 

Value  =>  value); 


PARAMETERS 

ada_variable 

The  name  of  the  Ada  variable  whose  value  the  user  wants  modified. 

value 

The  new  value  which  the  user  wishes  the  Ada  variable  to  have. 


DESCRIPTION 

The  SET  command  overwrites  the  current  value  of  the  Ada  variable  with  the 
value  specified  by  the  user.  The  value  specified  by  the  user  must  be  compatible 
with  the  type  of  the  Ada  variable. 

This  command  can  be  issued  to  set  up  process-controlling  parameters  before  the 
application  begins,  or  it  can  be  used  in  conjunction  with  the  READ  command  to 
fine-tune  the  system  as  it  is  running. 

Note:  Since  the  state  of  the  application  cannot  be  determined  when  the  operation 
is  performed,  this  command  should  be  used  cautiously. 


EXAMPLES 

O  Set (Name=>engine . rpm<,  Value=>4 000 . 00 ) ; 

Sets  the  value  of  engine. rpm  to  4000.00. 

©  Set  (engine. rpm,  4000.00); 

Same  as  the  above  example  without  named  association. 


START 


START 

Starts  collection  of  data  based  on  the  specified  page  of  Ada  variables  for  display. 

SYNTAX 

START  (Page  =>  page_spec, 

Update_Rate  =>  value); 

PARAMETERS 

-  pagespec 

Specifies  the  page  which  identifies  the  Ada  variables  to  be  collected  and  dis¬ 
played.  The  page_spec  may  contain  a  path  name  to  the  page. 

value 

Optional  parameter  which  specifies,  as  a  real  number,  the  rate  at  which  the  data 
are  collected  and  written  to  the  display  device.  The  default  value  is  2.0  seconds. 
The  usable  range  is  from  0.01  (once  every  hundredth  of  a  second)  to  60.0  (once 
every  minute). 


DESCRIPTION 

The  START  command  begins  collecting  the  values  of  the  Ada  variables  defined 
on  the  user-specified  page  and  displays  them  on  the  user’s  terminal.  The  rate  at 
which  the  data  are  displayed  is  user  controllable  by  specifying  the  Update_Rate 
parameter  (in  the  prototype,  the  display  update_rate  is  also  the  data  sampling 
rate).  If  this  optional  parameter  is  not  specified,  then  a  default  update  rate  of  two 
seconds  is  assumed. 

Prior  to  data  collection  each  variable  on  the  page  is  located  in  the  variable  data¬ 
base.  If  an  Ada  variable  is  not  available  for  examination  (i.e.,  it  is  not  in  the 
variable  database),  then: 

1 .  The  value  is  not  accessible 

2.  It  will  be  dropped  from  the  collection  list 

3.  An  error  message  will  appear  on  the  page  (i.e  ,  the  user’s  terminal) 
where  the  data  was  to  be  placed. 

EXAMPLES 

O  Start  (Page  m>  EngineVariables,  Update_Rate  «>  0.2); 

Starts  data  collection  of  the  Ada  variables  on  page  EngineVariables  and  displays 
them  on  the  default  display  device  with  the  data  being  updated  every  0  2 
seconds. 


EXCEPTIONS 


STOP 


DESCRIPTION 


The  STOP  command  terminates  the  collection  ol  data  based  on  a  page  which  is 
actively  collecting  data  tor  display  and  removes  the  page  from  the  screen. 


EXAMPLES 

©  Stop  (control _parameters)  ; 

Stops  data  collection  of  the  Ada  variables  on  the  page  control_parameters 
(assuming  a  START  command  for  the  page  has  been  previously  issued). 
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Appendix  B:  Generating  an  RTM  System 

This  appendix  outlines  the  basic  steps  that  are  needed  to  build  a  monitor  for  an  application 
Since  each  application  is  unique,  these  steps  must  be  repeated  for  every  application  because  it  is 
easier  to  customize  the  RTM  to  meet  the  needs  of  each  application  than  to  force  the  application 
into  a  set  mold  dictated  by  the  RTM. 

The  basic  steps  for  generating  the  RTM  system  are: 

•  Create  the  variable  database. 

•  Create  the  type  database. 

•  Create  the  compute_address  procedure. 

•  Customize  the  system  dependencies. 

•  Customize  the  processor  configuration. 

•  Tune  the  system  generation  parameters. 

•  Connect  the  RTM  and  application  together. 

Each  of  these  steps  is  discussed  in  detail  in  its  own  section  later.  All  of  these  steps,  with  the 
exception  of  the  tuning  step,  involve  changing  the  bodies  of  the  various  packages. 

Conventions  Used  in  This  Document 

The  conventions  used  in  this  document  are  listed  in  the  left-hand  column  below;  their  associated 
meanings  are  listed  in  the  right-hand  column. 

code  Ada  language  construct 

package  Ada  package  name 

subsystem  Ada  subsystem 

COMMAND  RTM  command 

B.l.  Create  the  Variable  Database 

The  creation  of  the  variable  database  involves  two  packages:  the  variable_database  package, 
which  is  responsible  for  creating  and  managing  the  variable  database  as  a  structure,  and  the 
library Jnterl ace  package,  which  is  responsible  for  generating  the  variable  information  stored  in 
the  database. 

Two  procedures  comprise  the  variable_database: 

inltlalize_database:  Creates  and  populates  the  database  (see  Figure  B-i) 
find:  Traverses  the  database. 

The  variable  database  is  built  automatically  by  Initial ize_Database  during  elaboration  of  the 
RTM.  These  routines  depend  on  the  interface  provided  by  the  library  intedace  package  and  do 
not  change  as  part  of  the  customization  of  the  RTM 
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with  Unchecked.Deallocation. 

-  Use  the  service  * 'uncheckedjdeattocation .  * 

with  Types.Manager, 

-  Use  the  service  "find" 

••pa rat*  (Variabte.Database) 
procedure  Initialize  Database  la 

-/ . . . 

-/  Description: 

-I  This  module  is  responsible  lor  building  the  variable  database 
-I  by  whatever  means  are  available. 

-/ 

-/  Parameter  Description: 

-/  none 
-/ 

-/  Notes: 

-/  AH  of  the  system  dependent  issues  related  to  obtaining 
-I  data  object  addresses  have  be  isolated  in  these  packages 
-I  Library_interface:  lor  static  data  inlormation. 

-I  Address_generator:  lor  dynamic  data  information. 

-I  These  are  the  packages  that  must  be  changed  to  reflect  the 
-I  system  configuration  and  environment. 

-/ . 

procadura  Free  Is  new  Unchecked.Deallocation 
( Library Jnterlace  Variable.Representation.The.Variable). 

VanaWe_Position:  Library _lnterfaoe  Variable Jterator. 

Node.Root  Db  Tree; 

Found. Variable:  Boolean; 

The.Next.Vanable  The  Vanable, 

begin 

-  The  basic  operation  is  the  same  for  aH  the  variables 

-  Build  a  vanable_representation  record 
Insert  the  record  into  the  tree 

-  Repeat  lor  all  variables 

Library  .Interface  Make_lterator(Variable_Position) ; 
while  Ubrary.lnterface  More(Variable.Position)  loop 

begin 

The.Next.Variable  :«  new  Library.lntertace  Variable.Representation, 
Library  .Interface  Get.Next 

(The.lterator  »>  Vanable.Position, 

Vanable.lntormation  «»  The.Next.Variable  all ), 
The.Next.Vanable  Data.Type  ;»  Types.Manager  Find 
(Name  «>  The.Next.Variable  Variable.Type), 

Db  lnsertnode(N  •>  The.Next.Variable. 

T  ->  Variable. Data  base. 

Root  «>  Node.Root. 

Exists  •>  Found. Variable); 

exception 

whan  Types.Manager  Type.Not.Found  »> 

Free  (The.Next.Variable), 

end  ; 

end  loop  ; 

end  Imtialize.Database 


Figure  B-1:  Initiallze.Database  Procedure 


The  libraryjnterface  is  responsible  lor  supplying  the  information  needed  by  the  RTM.  This  infor¬ 
mation.  as  a  minimum,  consists  of: 

variable.name:  The  full  Ada  path  name  of  the  variable.  This  path  name  must  go  to  the 
record  component  level  if  such  a  variable  is  to  be  available  for  monitoring. 

base_address:  The  static  address  of  the  variable  in  application  memory. 

type_name:  The  name  of  the  data  type  used  in  the  variable  declaration.  This  name  must 
match  the  character  string  used  to  identify  the  type  in  the  types_manager  package  (see 
Section  B.2). 

The  manner  in  which  this  information  is  generated  is  irrelevant  to  the  RTM.  To  illustrate  how  the 
libraryjnterface  package  is  used,  the  code  for  ln!tiallze_database  is  shown  in  Figure  B-l.  in 
words,  Figure  B-1  embodies  using  the  libraryjnterface  to  build  the  database;  these  steps  are: 

1.  Make  an  iterator  (using  makejterator). 

2.  While  there  are  more  variables  to  process  (indicated  by  a  true  value  for  more  loop): 

a.  get  the  next  variable  information  (varlable_representation  of  the  next  vari¬ 
able,  using  get_next) 

b.  get  the  type  of  the  variable  (using  find) 

c.  insert  the  variable  into  the  variable  database 

This  simple  algorithm  describes  the  entire  process  of  building  the  variable  database  and  il¬ 
lustrates  that  the  variable_dalabase  knows  nothing  about  the  data  in  the  structure  or  about  how 
the  data  are  generated.  Its  only  concern  is  that  the  information  is  supplied  using  the  interface 

variable_representation:  Type  that  supplies  the  variable  information  (outlined  above) 
plus  any  miscellaneous  information  needed  (or  available). 

make_Herator.  Responsible  for  doing  all  the  preparation  necessary  to  generate  variable 
information.  It  then  returns  an  iteration  control  variable  which  is  used  by  get_next  to  select 
the  next  variable  to  generate  information  on  and  by  more  to  determine  if  all  of  the  available 
variable  information  has  been  retrieved.  This  variable  is  private  to  the  libraryjnterface 
package  and  has  no  significance  outside  the  body  of  the  package:  therefore  it  can  be  used 
to  represent  anything  the  libraryjnterface  needs  internally  to  collect  the  variable  informa¬ 
tion. 

getjiext:  Takes  the  iteration  variable  and  generates  a  variable_representatlon  record 
The  manner  in  which  this  is  accomplished  is  irrelevant  to  the  RTM.  The  existing  version 
uses  standard  Ada  facilities  and  is  based  on  the  assumption  that  the  system  is  executing 
on  one  processor.  For  a  two-CPU  configuration,  some  kind  of  parsing  of  an  address  map 
would  have  to  be  substituted  for  this  body.  There  is  no  order  implied  by  the  manner  in 
which  variables  are  returned;  the  variable_cfatabase  package  simply  builds  the  structure  to 
tie  all  the  data  together. 


More:  takes  the  iteration  variable  and  returns  a  true  value  when  more  variables  are  avail¬ 
able  and  a  false  value  when  all  the  variables  have  been  processed.  Again,  the  exact 
nature  ot  how  this  is  determined  is  dependent  on  how  the  variable  information  is  generated. 


The  approach  used  in  the  prototype  is  applicable  only  to  a  single  processor  configuration.  In  this 
approach,  the  libraryjnterface  "withs"  in  all  the  packages  of  interest  to  the  user.  The  package 
then  lists  all  the  variables  visible  along  with  their  Ada  data  types;  the  ’address3  attribute  is  then 
used  to  return  the  address  of  the  variable  (as  an  integer).  The  code  that  implements  the 
libraryjnterface  package  for  this  case  is  shown  in  Figure  B-2.4  Clearly,  this  approach  has  some 
severe  restrictions: 

•  Only  package-level  objects  can  be  monitored  (no  local  or  package-body  data  are 
visible). 

•  It  does  not  work  in  a  multiple  processor  system. 

•  Every  item  to  monitor  must  be  placed  in  the  database  by  hand;  this  implies  that  all 
record  components  and  array  references  must  be  expanded  (which  creates  an  un¬ 
necessarily  large  database). 

A  number  of  other  solutions  to  the  database  problem  are  possible,  and  in  fact  must  be  actively 
pursued  for  multiple  CPU  systems.  Something  as  simple  as  a  linker  load  map  showing  where  all 
the  static  variables  are  allocated  can  be  parsed  and  used  to  populate  the  variable  database. 
Clearly,  a  better  solution  (possibly  the  best  solution)  is  access  to  the  compiler  and  linker  oulput 
used  by  a  symbolic  debugger.  The  availability  of  this  level  of  detailed  information  vastly  in¬ 
creases  the  number  ol  items  that  can  be  monitored  and  reduces  the  tedium  that  the  prototype 
approach  implies. 


B.2.  Create  the  Type  Database 

The  typesjmanager  package  contains  all  the  type  information  that  the  RTM  needs  to  know. 
When  we  discuss  types,  we  are  referring  to  the  Ada  data  types  associated  with  the  variables  in 
the  variable  database.  To  be  in  the  variable  database,  a  variable's  declared  data  type  must  be  in 
the  type  database;  without  this  correspondence,  the  RTM  does  not  know  enough  about  the  vari¬ 
able  to  extract  it  from  the  application  or  display  it  to  the  user. 

The  type  database  is  entirely  constructed  by  hand  (again,  access  to  compiler-generated  infor¬ 
mation  would  alleviate  this  problem)  primarily  because  informing  the  RTM  about  a  new  type 
requires  program  changes  to  the  body  of  types_manager.  The  best  way  to  illustrate  the  infor¬ 
mation  needed  by  the  types_manager  is  to  examine  the  code  fragment  shown  in  Figure  B-3. 

The  type  information  is  held  in  two  structures:  valld_type_name  and  type_representatlon.  The 
explanation  and  examples  shown  in  Figure  B-3  illustrate  how  a  type  is  entered  into  the  database: 


3Care  must  be  taken  in  the  use  of  'address  attribute  since  it  may  need  to  be  adjusted  to  obtain  the  true  address  of  the 
data 

4This  approach  has  to  be  entirely  crafted  by  hand  and  is  not  the  recommended  approach 
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with  System; 

-  Use  type  * address 

with  Unchecked_Conversion; 

-  Use  service 'unchecked_conversion.‘ 

with  Test_Stub; 

-  Use  data  objects  defined  here  for  testing  the  monitor. 


package  body  Library Jnterface  ia 

-  Used  to  convert  all  the  system  addresses  into  integers  so  that 

-  they  can  be  stored  in  the  variable  database.  In  a  system  where 

-  an  address  map  is  used,  this  routine  will  need  to  be  reimplemented. 

function  Get_Address  is  new  Unchecked_Conversion 
(Source  =>  System. Address, 

Target  =>  Integer); 


procedure  Makejterator  (Thejterator:  in  out  Variablejterator)  it 

begin 

Thejterator :«  0; 
end  Makejterator. 


procedure  Get_Next  (Thejterator;  In  out  Variablejterator; 

Variable Jnformation:  out  Variable_Representation)  It 

begin 

cate  Thejterator  it 
when  0  «> 

Variablejntormation  Variable_Name(l.,20) :» "test_stub.myjnteger"; 
VariableJntormation.Base_Address  :»  Get_Address(Test_Stub.MyJnteger'Address); 
Variablejntormation. Variable_Type(1.. 7)  :=  "integer"; 

when  1  •> 

Variablejntormation. Variablejslametl..  17) :«  "test_stub.my_rear; 
Variable_lnformation  Base  Address  :■  Get_Address(Test_Stub  My_Real  Address); 
Variablejntormation. Variable_Type(1. 5)  :=  "float"; 

when  others  ■> 
null  ; 

end  cate ; 

Thejterator  >  Thejterator  +  1 ; 
end  Get_Next; 


function  More  (The_lterator:  in  Variablejterator)  return  Boolean  it 
begin 

if  The  Iterator  <«  1  then 
RETURN  True; 

else 

RETURN  False; 
end  H; 
end  More; 

end  Library Jnterface; 

Figure  B-2:  Example  of  Generating  Variable  Information 
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•  An  enumeration  name  for  the  type  is  created  (in  valid_type_name). 

•  A  representation  record  for  the  type  is  created  (in  type_representation). 

•  A  string  name  is  defined  for  the  type  in  the  package  body  (this  is  the  name  returned 
by  library Jnterface). 

The  only  restriction  on  types  is  that  enumeration  types  (from  the  application  being  monitored) 
must  be  declared  in  the  body  of  package  types_managert  this  can  be  done  by  "withing"  in  the 
package  that  declares  the  type  or  by  manually  redefining  the  type.  This  restriction  does  not  apply 
to  integers  and  floats,  since  they  are  universal  base  types. 

Once  the  type  is  defined,  the  generic  conversion  routine  for  the  base  type  must  be  instantiated  for 
the  new  type  (the  converljntegers  generic  is  shown  in  Figure  B-4).  The  generic  is  instantiated 
with  the  source  type  (a  type  that  the  RTM  understands),  a  default  display  width,  and  a  low-level 
conversion  procedure  (shown  in  Figure  B-5).  After  instantiation,  integer  bit  strings  can  be  con¬ 
verted  to  display  strings  by  reference  to  rtm_integers.make_string  (shown  in  Figure  B-6),  or  a 
string  can  be  converted  to  a  bit  string  by  using  rtm_fntegers.make_value  (also  shown  in  Figure 
B-6).  The  complete  version  of  the  case  statements  shown  in  Figure  B-6  contains  an  entry  for 
every  type  defined  in  valid_type_name  and  invokes  the  generic  instantiation  appropriate  for 
each  type. 

\ 

Finally,  the  default_integer_convers!on  procedure  shown  in  Figure  B-5  is  critical  for  proper 
multi-CPU  processing.  In  a  single  CPU  system,  the  approach  shown  in  Figure  B-5  is  correct  — 
that  is,  take  an  address  and  return  the  integer  at  that  address.  In  a  multi-CPU  system,  this  may 
not  be  correct,  especially  when  the  underlying  type  representation  is  different  between  the  RTM 
processor  and  the  application  processor(s).  This  situation  requires  the  conversion  routine  to  map 
the  target  (application  processor)  bit  representation  into  the  host  (RTM  processor)  bit  represen¬ 
tation.  It  is  the  responsibility  of  this  low-level  function  to  supply  the  generic  conversion  package 
with  a  bit  representation  it  understands. 


B.3.  Create  the  Compute_Address  Procedure 

The  compute_address  procedure  is  an  important  abstraction  for  the  system  since  it  combines 
the  information  from  the  variablejdatabase  and  the  types_manager  to  generate  effective  ad¬ 
dresses  for  variables.  In  the  simple  case  used  by  the  prototype  (shown  in  Figure  B-7),  address 
computation  simply  requires  that  the  variable  be  located  in  the  variable  database  and  its  base 
address  returned  (since  every  available  variable  and  its  base  address  are  in  the  database).  In  a 
more  sophisticated  case,  where  a  debugger  interface  is  available  or  a  more  powerful  parser  is 
used  (implying  that  address  offsets  are  computed),  the  compute_address  procedure  can  be 
modified  to  accommodate  this  without  impacting  the  RTM  code.  This  isolation  of  address  compu¬ 
tation  allows  for  more  powerful  methods  to  be  incorporated  as  they  become  available. 
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package  body  Types_Manager  ia 

-  Define  the  names  of  all  the  legal  types. 

type  Valid_Type_Name  ia  (Integers,  Floats,  Rtm_Enum1,  Rtm_Record), 

-  Define  all  the  data  needed  about  each  type: 

-  type_name_as_string  ■>  A  character  string  version  of  the  type  name. 

-  This  must  match  exactly  with  the  type  as  it 

-  exists  in  the  application  program,  where  the 

-  type_name  is  a  convenient  enumeration  literal 

-  lor  this  type. 

-  type_name  ->  An  enumeration  literal  for  the  type. 

-  type_length  ->  The  size  of  the  type  in  smallest_umts. 

-  display_wictth  ->  Number  of  characters  needed  to  display  a  value 

-  of  the  type:  integer  :=  25: 

-  indirection_level  ■>  An  integer  that  indicates  how  many  levels  of 

-  indirect  access  the  type  represents. 

type  Type_Representation  ia  record 
Type_Name_As_String:  String(1 .256); 

TypeName  Valid_Type_Name; 

Type_Length:  Integer  =0; 

Display_Widlh:  Integer  :=  25; 
lndirection_Level  Integer  >  0; 
end  record  ; 

-  Define  the  table  that  holds  all  the  type  information:  define 

-  type_name_as_string  in  body. 

Number_Of_Valid_Types:  Va!id_Rtm_Type  :«  4; 

Valid_Rtm_Types:  array  (1..Number_OM/alid_Types)  of  Type_  Re  presentation  ■ 
((Type_Name_As_String  =>  (others  *=>  ' '), 

Type_Name  »>  Integers,  Type_Length  «>  1, 

Display_Width  «=»  10,lndirection_Level  =>  0). 

(Type_Name_As_String  «>  (others  => ' '), 

Type  Name  *>  Floats.  Type_Length  =>  1 , 

Display_Width  =>  10,lndlrection_Level  =>  0). 

(Type_Name_As_String  »>  (others  => ' '). 

Type_Name  »>  Rtm_Enum1,  Type_Length  =>  1, 

D«play_Width  «>  5,lndirection_Level  «>  0), 

(Type_Name_As_String  •>  (others  *>  ' '). 

Type_Name  »>  Rtm_Record,  Type_Length  =>  2, 

Display_Width  =>  20,lndirection_Level  «>  0)); 


-/ . 

-I 

~l  Package  Body 
-I 

-I  The  body  is  responsible  for  initializing  the  string  versions 
-I  of  all  the  type  names. 

-I 

-I . 

begin 

Valid_Rtm_Types(1).Type_Name_As_String(1..7)  >  "integer”; 
Valid_Rtm_Types(2).Type_Name_As_String(1..5)  :« 'float”; 
Valid_Rtm_Types(3).Type_Name_As_String(1..9)  :« 'rtm_enumf; 
Valid_Rtm_Types(4)Type_Name_As_String(1  10)  >  'rtm_record'; 
end  Types_Manager, 

Figure  B-3:  Code  Fragment  That  Detines  a  Type  Database  Entry 


i  All  VI  «I1 


with  System; 

-  Need  the  type  "Address  ‘ 
package  Conversions  la 

-  Signals  that  the  value  in  the  character  string  is  the  wrong  type 

-  lor  the  variable. 

lllegal_Value:  exception  ; 
generic 

-  Default  Width  of  the  generated  character  strings. 

Width;  Positive  15; 

-  Integer  type  source,  This  is  the  host  machine's  type, 
type  Source_Representation  is  range  <>; 

-  Low-level  conversion  routine  needed  to  convert  from  the  target 
--  representation  to  the  host  representation  of  the  source  type. 

-  (referred  to  as  source_representation) 

with  function  Target_Conversion  (Raw_Value:  in  System  Address) 
return  Source_Representation; 


package  generic  package  Convertjntegers  is 

procedure  Make_Stnng  (Raw_Value:  in  System  Address. 
Field_Size:  in  Integer; 

Value:  out  String); 

-/ . 

-/  Description: 

-/  Make_string  takes  a  binary  bit  string  and  converts  it  into 
-I  an  integer  character  string. 

-I 

-I  Parameter  Description: 

-I  rawvalue  ->  The  address  of  the  binary  bit  string  to  be 
--/  converted. 

-/  lield_size  ■>  The  number  ol  characters  needed  in  the  output 
-/  string. 

-/  value  ->  The  character  image  ol  the  binary  bit  siring  as 
-I  an  integer. 


procedure  Make_Value  (Raw_Value:  In  String, 

Value:  In  System. Address); 

-/ . 

-/  Description: 

~l  Make_value  takes  an  integer  character  string  and  converts  it  into  a 
-/  binary  bit  string. 

-I 

-I  Parameter  Description: 

~l  raw_value  ->  The  character  string  to  be  converted 
~l  value  ->  The  address  where  the  resulting  bit  string  is  to  be 
-I  stored. 

-I . . . 

end  Convertjntegers; 


end  Conversions; 


Figure  B-4:  Generic  Conversion  Package  for  Integers 
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with  Conversions; 
package  body  Types_Manager  la 
type  lnteger_Pointer  la  acceaa  Integer; 

function  Address_To_lnteger_Pointer  la  new  Unchecked_Conversion 
(Source  ■=>  System.Address, 

Target  =>  lnteger_Pointer); 

function  Default_lnteger_Conversion  (Raw_Value:  in  System.Address) 
return  Integer  la 

-/ . 

--/  Description: 

-/  Convert  from  a  bit  string  at  a  system  address  to  an  integer 
-/  value.  This  is  valid  for  a  one-CPU  configuration 
--/  only. 

-I 

-/  Parameter  Description: 

~l  raw  value  ->  The  address  of  the  bit  string  to  convert. 

--/ . 

Value_Pointer:  lnteger_Pointer; 

begin 

Value_Pointer  :=  Address_To_lnteger_Pointer(Raw_Value); 

RETURN  Value_Pointer.all ; 
end  Default_lnteger_Conversion; 
pragma  Inline  (Default_ln!eger_Conversion); 

-  Create  the  package  to  convert  from  bit  strings  to  integers. 

package  Rtmjntegers  ia  new  Conversions  Convert  Integers 
(Width  =>  15. 

Source_Representation  =>  Integer, 

Target_Conversion  =>  Default_lnteger_Conversion); 

end  Types_Manager; 


Figure  B-5:  Code  Fragment  That  Instantiates  Integer  Conversions 


B.4.  Customize  the  System  Dependencies 

One  system  dependency  that  must  be  addressed  is  the  virtual  terminal  interface.  This  interlace  is 
based  on  a  Unix  termcap  style  definition  file  for  controlling  the  terminal  functions.  This  definition 
file  is  tcf.tcf.  This  file  is  already  set  up  for  a  VT100  style  terminal;  therefore,  the  existence  of  a 
VT100  emulation  mode  will  greatly  facilitate  the  rehosting  of  this  subsystem. 

Package  sysdepjbody  is  the  only  VAX  VMS-dependent  package.  It  is  used  exclusively  to  do 
synchronous  and  asynchronous  character  I/O  to  the  user’s  terminal.  This  package  is  part  of  the 
virtual  terminal  interface,  and  the  body  will  need  to  be  reimplemented  to  operate  in  a  non- VAX 
VMS  environment. 

Package  sysdep_bodf  is  written  in  Ada  and  executes  under  VMS.  At  the  lowest  level  of  imple¬ 
mentation,  it  uses  the  VMS  system  services.  A  system  servicp  call  is  issued  to  create  a  channel 


'This  package  boby  is  part  o(  the  virtual  terminal  subsystem  {Texas  instruments  85b) 
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separate  (Types_Manager) 

procedure  Convert_String_To_Value  (Data_Type  In  Valid_Rtm_Type, 
Raw_Data:  In  System  Address; 

The_Value;  In  String)  is 

begin 

case  Valid_Rtm_Types(Data_Type).Type_Name  la 
when  Integers  -> 

Rtm_lntegers.Make_Value  (The_Value,Raw_Data); 
when  other*  «> 
null ; 

end  case; 

exception 

when  Conversions. Illegal  Value  ■> 

RAISE  lllegal_ Value; 
when  others  <> 

RAISE  ; 

end  Convert_String_To_Value; 


separate  (Types_Manager) 

procedure  Convert_Value_To_String  (Data_Type  in  Valid_Rtm_Type, 

Raw_Data:  In  System  Address, 

Number_Of_Characters  In  Integer; 

The_Value:  out  String)  Is 

begin 

[  The_Value  :«  (The_Value'range  «>  ' '); 

case  Valid_Rtm_Types(Data_Type).Type_Name  Is 
when  Integers  «> 

Rtmjntegers  Make_String  (Raw_Value  <=>  Raw_Data, 

Field_Size  «>  Number_Of_Criaracters, 

Value  =>  The_Value). 

when  others  «> 
null  ; 

end  case ; 

end  Convert_Value_To_String; 

Figure  B-6:  Code  Fragment  That  Performs  Integer  Conversions 

to  a  device,  and  QIO  calls  are  issued  to  perform  character  read  and  write  operations  on  the 
device.  Starlet  and  Condition_Handling  are  VAX  Ada  library  packages  that  allow  easy  interfacing 
of  the  VMS  system  services  to  the  RTM. 


Since  the  system  dependencies  are  all  tied  to  VAX  VMS,  a  few  words  on  rehosting  to  a  Unix 


environment  are  in  order.  First,  to  rehost  to  a  UNix-based  system,  all  the  QIO  system  calls  must 
be  replaced.  UNix-equivalent  system  calls  will  replace  the  VMS  service  calls  in  procedures  open, 
get,  and  put  of  package  sysdep_body.  VMS’s  I/O  channels  might  be  considered  equivalent  to  a 
File  Descriptor  in  Unix  with  access  to  the  keyboard  established  by  using  the  Unix  open  system 
call.  Character  level  reads  and  writes  to  the  terminal  can  be  performed  using  textjo  procedures 
after  setting  the  keyboard  to  "RAW"  mode  (via  an  toctt  call);  this  will  allow  characters  to  be 
obtained  unedited  from  the  keyboard  driver  without  a  terminating  carriage  return  (or  newline);  the 
virtual  terminal  subsystem  and  forms  management  subsystem  perform  all  character  inter¬ 
pretation. 


function  Compute_Address  (Variable_Name:  In  String) 
return  Address_Representation  it 

-I . 

-/  Description: 

-I  This  module  takes  the  database  identifier  of  a  variable  and 
-/  computes  the  address  of  the  variable. 

-I 

-/  Parameter  Description: 

— /  the_variable  ->  Name  of  variable  for  which  address  is  needed. 

-I  return  ->  Computed  address  of  the  variable. 

-I 

-/  Notes: 

-/  No  address  offset  is  computed  since  all  accessible  variables  are 
-/  in  the  database,  and  the  base_address  already  has  the  offset 
-/  taken  into  account. 

-I . 

The_Variable:  Variable_Database.The_Variable; 

Address:  Address_Generator  Address_Representation  :=  Nul!_Address; 
Address_Odset:  constant  Integer  :=  0; 

Data_Length:  Integer; 

Access_Flag:  Boolean; 
begin 

The_Variable  :=>  Variable_Database  Find(Vanable_Name); 
Types_Manager.Get_Type_lnlormation  (The_Variable.Data_Type, 
Data_Length, 

Access_Flag); 

Address  :«  (The_Variable  Base_Address. 

Address_Ottset, 

Access_Flag); 

RETURN  Address 
end  Compute_Address; 


Figure  B-7:  Simple  Compute_Address  Procedure 


B.5.  Customize  the  Processor  Configuration 

The  RTM-to-application  interface  is  handled  by  the  rtm_core  module.  On  a  single  CPU.  the 
prototype  is  currently  setup  correctly.  For  a  two-CPU  configuration,  the  rtm_core  package  will 
need  to  be  duplicated.  One  copy  will  reside  with  the  RTM  on  the  host  processor,  and  the  second 
copy  will  reside  with  the  application  on  the  target  processor 


On  the  host  processor,  the  processing  in  the  process_buffer  module  needs  to  be  removed  and 
should  look  like  Figure  B-8.  The  following  need  to  take  place: 

1 .  Transfer  the  command  and  data  buffers  to  the  target,  and 

2.  Wait  for  the  command  and  data  buffers  to  become  available. 


There  are  two  stubbed  modules.  send_buffer  and  get_buffer,  which  need  to  be  implemented  to 
accomplish  this  transfer. 


On  the  target  processor,  the  process_buffer  module  needs  to  be  integrated  into  the  top-level 
executive  or  the  timing  controller  of  the  application.  It  is  then  given  an  execution  time-slice 
periodically.  During  this  time -slice  it  will: 

1 .  Look  for  the  availability  of  a  command  buffer. 

2.  Process  all  the  commands  in  the  buffer  (this  is  why  the  core_buffer_size 
parameter  is  so  critical:  it  controls  the  maximum  amount  of  time  the  rtm_core  will 
ever  use  to  execute). 

3.  Mark  the  buffer  as  available  and  transfer  it  back  to  the  host. 

Again,  the  send_buffer  and  get_buffer  modules  must  be  implemented  to  correctly  complete 
transferring  the  buffers  between  the  processors  (which  is  not  a  trivial  exercise). 


B.6.  Tune  the  System  Generation  Parameters 

The  parameters  available  for  tailoring  the  RTM  to  suit  the  local  environment  are  contained  in  the 
package  sysgen.  They  are: 

smallest_unlt:  The  type  which  represents  the  smallest  addressable  or  most  efficiently 
addressable  unit  on  the  target  processor.  All  type  sizes  (discussed  in  Section  B.2)  are 
defined  in  terms  of  this  unit.  For  example,  on  the  VAX  running  VMS,  the  most  efficient 
addressable  unit  is  a  32-bit  word  or  the  standard  integer;  thus  all  types  in  the  RTM  type 
database  are  defined  as  multiples  of  this  32-bit  "smallest  unit." 

core_buffer_size:  The  size  of  the  command  and  data  buffers  that  communicate  between 
the  RTM  and  the  rtm_core  (which  resides  in  the  target  processor  along  with  the 
application).  This  limits  the  number  of  deposit  and  extract  operations  that  the  rtm_core  can 
process  during  a  time-slice  and  should  be  tailored  to  reflect  the  minimum  time-slice  that  the 
rtm_core  will  have  available. 

processor_count:  The  number  of  processors  being  used  in  the  system.  It  is  either  one  or 
two  (a  two  implies  that  the  work  discussed  in  the  Section  B.5  must  be  implemented). 

default_rtm_device:  The  default  disk  directory  where  the  RTM  will  look  for  page  files, 
unless  an  explicit  path  name  is  supplied. 
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B.7.  Connect  the  RTM  and  Application  Together 

Once  all  the  previously  discussed  customizations  are  in  place,  the  tinal  piece  of  work  is  connect¬ 
ing  the  RTM  and  application  together  to  form  a  working  system.  The  exact  nature  of  this  connec¬ 
tion  depends  on  the  number  of  processors  in  the  system.  We  will  show  an  example  from  the 
single  processor  case  and  discuss  the  extensions  needed  for  the  multiple  processor  case. 

The  simplest  way  to  connect  the  system  together  is  shown  in  Figure  B-9  (this  example  assumes  a 
non-real-time  application).  This  example  illustrates  the  key  steps: 

1.  real_tlme_monitor.setup_rtm  must  be  invoked  before  invoking  the  RTM,  since 
this  performs  all  the  system  initializations  required  by  the  RTM. 

2.  real_time_monitor.rtm  invokes  the  RTM  for  one  pass  of  its  processing  loop.  Two 
points  to  note  about  this  interaction  are: 

•  If  the  user  is  entering  a  command,  control  will  not  return  to  the  application 
program  until  after  the  command  has  been  entered  and  processed. 

•  If  a  page  is  active,  one  page  update  will  occur  (assuming  it  is  time  to  update 
the  page). 

3.  real_time_monitor.termlnate_rtm  exception  signals  that  a  QUIT  command  has 
been  issued  and  indicates  that  a  call  real_tlme_monitor.closeout__rtm  is  required 
(to  properly  exit  the  RTM). 

This  approach  to  connection  only  works  well  with  non-real-time  applications  because  there  is  no 
mechanism  to  control  the  amount  of  time  the  RTM  uses. 

with  Text_lo;use  Texijo; 

with  Test_Stub; 

with  Real_Time_Monitor; 

procedure  Appl  is 

begin 

loop 

Test_Stub  Go; 

begin 

Real_T ime_Monitor  Rtm ; 

exception 

when  Real_Time_Monitor.Terminate_Rtm  *> 

Put_LinefRTM  terminated,  application  still  running’); 

end  ; 

end  loop ; 
end  Appl; 

Figure  B-9:  Application  to  RTM  Connection 

In  a  real-time  situation  on  a  single  processor  (i.e.,  both  the  RTM  and  application  are  running  on 
one  CPU),  the  application  and  RTM  must  be  individually  invoked  from  an  operating  system  task 
that  has  the  ability  to  time-slice  the  two  processes.  The  application  must  be  allowed  to  execute 
as  required.  The  RTM  is  executed  and  suspended  as  time  permits  (i.e.,  whenever  the  application 
is  idle  and  has  signaled  this  fact  to  the  operating  system  task). 

The  multiple  processor  situation  implies  a  critical  need  for  real-time  execution  of  the  application. 


In  many  respects  this  is  the  simplest  case.  In  this  situation,  the  RTM  (modified  as  described  in 
Section  B.5)  can  be  executing  on  its  own  CPU  and  communicating  with  the  application  (which  is 
executing  on  one  or  more  CPUs)  over  a  high-speed  bus.  This  allows  everything  to  execute  as 
needed,  with  minimum  perturbation  of  the  application  and  no  slow  down  in  the  RTM's  user  inter¬ 
face. 
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